This project was created to ease other's journeys in creating their own custom async executors. The code base respectfully derives from other developers in futures-rs (the license is in their names). The aim is to provide the most absolute minimal waker system and provide clarity into how one of the most challenging parts of how async-await works.
Beginners: To see a super simple single task executor check out the example
To see a complete multi task async-await and executor check out the howdy example
How does Async-Await work?
This section is meant for people who are complete beginners.
A future is an object that usually starts some long term activity (like a timer!). It can be asked about its current state (polling), returning either "Ready!" or "I'm still working, don't bother me!". Futures can depend on other futures to complete, creating a chain of polling.
An executor is an object that contains a list of futures that need to be polled. It goes through them one by one and asks "hey, are you done yet?" (polling). Each time a future is polled, the executor gives it a waker so that the executor can check back in on it later when the future says its ready!
A task is simply a top most level future. Executors will poll on a list of task futures that will poll their child executors. Don't worry though async { } auto generates most of that heirarchal future dependency magic!
A waker is an object that can later call a function on an object that will tell the executor "hey, put me back on your list of things to do!". It uses a lot of pointer magic and is arguably the most mind-bendy aspects of async-await (and the reason woke was written)!
A context is simply a holder of a waker (and maybe other things in the future!). It's how the executor gives the waker to the future when it polls.
Usage
Add this to your Cargo.toml:
[]
= "0.0.3"
The current async-await feature requires Rust 1.39 or later.
License
This project is licensed under either of
- Apache License, Version 2.0, (LICENSE-APACHE or http://www.apache.org/licenses/LICENSE-2.0)
- MIT license (LICENSE-MIT or http://opensource.org/licenses/MIT)
at your option.
Contribution
Unless you explicitly state otherwise, any contribution intentionally submitted for inclusion in woke by you, as defined in the Apache-2.0 license, shall be dual licensed as above, without any additional terms or conditions.